<!DOCTYPE html>
<html>
  <head>
    <title>jslint4java ant task</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <link href="jslint4java.css" type="text/css" rel="stylesheet" />
    <link href="prettify.css" type="text/css" rel="stylesheet" />
    <script type="text/javascript" src="prettify.js"></script>
  </head>
  <body>
    <h1>jslint4java ant task</h1>
    <p>
      jslint4java provides an <a href="http://ant.apache.org/">ant</a> task so
      that it can be invoked automatically as part of your build procedure.  For
      more detail on precisely what is checked, please see
      <a href="http://jslint.com/lint.html">the original documentation</a>.
      To get started quickly, see the <a href="#examples">examples</a>.
    </p>

    <p>jslint4java requires Java 5 and ant 1.7.</p>

    <h2 id="parameters">Parameters</h2>
    <table>
      <tr>
        <th> Attribute </th>
        <th> Description</th>
        <th> Required? </th>
      </tr>
      <tr>
        <td> encoding </td>
        <td> Specify the encoding of the JavaScript files. Defaults to system encoding. </td>
        <td> No </td>
      </tr>
      <tr>
        <td> failureProperty </td>
        <td> The name of a property to set in case of build failure.   You should also set <code>haltOnFailure="false"</code>. </td>
        <td> No </td>
      </tr>
      <tr>
        <td> haltOnFailure </td>
        <td> Should the build stop if JSLint reports an error?  Defaults to true. </td>
        <td> No </td>
      </tr>
      <tr>
        <td> jslint </td>
        <td> The path to an alternative <code>jslint.js</code>.  If you want to use a newer version than the bundled one. </td>
        <td> No </td>
      </tr>
      <tr>
        <td> options </td>
        <td> A comma separated list of options to pass to JSLint. </td>
        <td> No </td>
      </tr>
    </table>
    <p>
      The valid list of options is defined by the
      <a href="apidocs/com/googlecode/jslint4java/Option.html">Option</a> enum,
      and comprises of:
    </p>
    <dl>
      <dt>adsafe     <dd>If adsafe rules should be enforced
      <dt>bitwise    <dd>If bitwise operators should not be allowed
      <dt>browser    <dd>If the standard browser globals should be predefined
      <dt>cap        <dd>If upper case html should be allowed
      <dt>continue   <dd>If the continuation statement should be tolerated
      <dt>css        <dd>If css workarounds should be tolerated
      <dt>debug      <dd>If debugger statements should be allowed
      <dt>devel      <dd>If logging should be allowed (console, alert, etc.)
      <dt>es5        <dd>If es5 syntax should be allowed
      <dt>evil       <dd>If eval should be allowed
      <dt>forin      <dd>If for in statements need not filter
      <dt>fragment   <dd>If html fragments should be allowed
      <dt>indent     <dd>The indentation factor
      <dt>maxerr     <dd>The maximum number of errors to allow
      <dt>maxlen     <dd>The maximum length of a source line
      <dt>newcap     <dd>If constructor names must be capitalized
      <dt>nomen      <dd>If names should be checked
      <dt>on         <dd>If html event handlers should be allowed
      <dt>onevar     <dd>If only one var statement per function should be allowed
      <dt>passfail   <dd>If the scan should stop on first error
      <dt>plusplus   <dd>If increment/decrement should not be allowed
      <!-- NB: predef omitted as it has its own child element. -->
      <dt>regexp     <dd>If the . should not be allowed in regexp literals
      <dt>rhino      <dd>If the rhino environment globals should be predefined
      <dt>safe       <dd>If use of some browser features should be restricted
      <dt>strict     <dd>Require the "use strict"; pragma
      <dt>sub        <dd>If all forms of subscript notation are tolerated
      <dt>undef      <dd>If variables should be declared before used
      <dt>white      <dd>If strict whitespace rules apply
      <dt>widget     <dd>If the yahoo widgets globals should be predefined
      <dt>windows    <dd>If ms windows-specigic globals should be predefined
    </dl>

    <p>
      If a parameter is required (as in the case of <em>indent</em>), then it can
      be supplied by appending an equals and the value.  e.g. <code>indent=2</code>.
    </p>

    <h2 id="Parameters_specified_as_nested_elements">Parameters specified as nested elements</h2>

    <h3 id="resource-collection">resource collection</h3>

    <p>
      Any kind of
      <a href="http://ant.apache.org/manual/Types/resources.html#collection">resource collection</a>
      may be specified as a subelement.  Most of the time, this will mean a
      <a href="http://ant.apache.org/manual/Types/fileset.html">fileset</a>.
    </p>

    <h3 id="formatter">formatter</h3>

    <p>
      Zero or more formatter elements may be specified in order to control
      output from jslint.  Each formatter element has two attributes.
    </p>

    <table>
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Required</th>
      </tr>
      <tr>
        <td> type </td>
        <td>
          <dl>
            <dt><code>plain</code></dt>
            <dd>Produces three lines of text output per error.  Shows location and evidence.</dd>
            <dt><code>xml</code></dt>
            <dd>Creates a single XML file describing all errors seen in the input.  This is a custom XML format for jslint4java.  You should prefer the JUnit xml formatter instead.</dd>
            <dt><code>junit</code></dt>
            <dd>Creates a directory full of junit xml files.  These can be integrated into existing continuous build systems such as <a href="http://hudson-ci.org/">hudson</a> or <a href="http://zutubi.com/products/pulse/">pulse</a>.</dd>
            <dt><code>checkstyle</code></dt>
            <dd>Creates a single file XML, listing all errors seen in the input.  This should be compatible with checkstyle's <a href="http://checkstyle.hg.sourceforge.net/hgweb/checkstyle/checkstyle/file/623dba645830/src/checkstyle/com/puppycrawl/tools/checkstyle/XMLLogger.java">XMLLogger</a>.</dd>
            <dt><code>report</code></dt>
            <dd>Makes an HTML file containing one <a href="http://www.jslint.com/lint.html#report">JSLint report</a> per input file.</dd>
          </dl>
        </td>
        <td> Yes </td>
      </tr>
      <tr>
        <td> destfile </td>
        <td> A location to write the output to.
          <ul>
            <li>For the <code>plain</code> formatter, you can redirect output to a file.  If you leave this attribute out, then output will appear on the console.</li>
            <li>For the <code>xml</code> and <code>report</code> formatters, you have to specify a file to write the output to.</li>
            <li>For the <code>junit</code> formatter, you have to specify a directory.  Each file linted will have one file created in that directory.</li>
          </ul>
        </td>
        <td> No </td>
      </tr>
    </table>

    <p>
      If no formatter elements are present, then no output will be produced.
      However, the build will still fail if the validation fails.
    </p>

    <h3 id="predef">predef</h3>

    <p>
      You can specify a comma separated list of global variables inside a
      <code>&lt;predef&gt;</code> element.  This can be useful for functions
      that you know are globally available in your environment, e.g.
      <code>jQuery</code>.
    </p>

    <h2 id="examples">Examples</h2>

    <p>
      First, you need to define the task in your build file.
    </p>

    <pre class="prettyprint" id="example-taskdef">  &lt;taskdef name="jslint"
           classname="com.googlecode.jslint4java.ant.JSLintTask"
           classpath="/path/to/jslint4java-1.4.7.jar" /&gt;</pre>

    <p>
      You may also use the antlibs facility to pull in JSLint.
    </p>

    <pre class="prettyprint" id="example-xmlns">  &lt;project xmlns:jsl="antlib:com.googlecode.jslint4java"&gt;
    …
  &lt;/project&gt;</pre>

    <p>
      Doing so will require you to access the <code>jslint</code> task as
      <code>jsl:jslint</code>.  This also means that you have to install
      <code>jslint4java-1.4.7.jar</code> in
      <code>~/.ant/libs</code>.
    </p>

    <p>
      If you want to keep the jslint4java jar checked in as part of your
      project, you have to combine the above two approaches. For example,
      assuming you have placed the jar in <code>lib-build</code>:
    </p>

    <pre class="prettyprint" id="example-checkedin">&lt;project xmlns:jsl=&quot;antlib:com.googlecode.jslint4java&quot;&gt;
  &lt;path id=&quot;ant.tasks.classpath&quot;&gt;
    &lt;fileset dir=&quot;lib-build&quot; include=&quot;*.jar&quot; /&gt;
  &lt;/path&gt;
  &lt;taskdef uri=&quot;antlib:com.googlecode.jslint4java&quot;
           resource=&quot;com/googlecode/jslint4java/antlib.xml&quot;
           classpathref=&quot;ant.tasks.classpath&quot; /&gt;
  &hellip;
&lt;/project&gt;</pre>

    <p>
      Again, this means you have to refer to the task as <code>jsl:jslint</code>.
    </p>

    <p>
      To check a directory for all <code>.js</code> files, and emit all errors to
      the console:
    </p>

    <pre class="prettyprint" id="example-all-js">  &lt;jslint&gt;
    &lt;formatter type="plain" /&gt;
    &lt;fileset dir="web/js" includes="*.js" /&gt;
  &lt;/jslint&gt;</pre>

    <p>
      To check a directory for all <code>.js</code> files, excluding packed files.
      Send any problems to a file <code>jslint.out</code>.
    </p>

    <pre class="prettyprint" id="example-plain-file">  &lt;jslint&gt;
    &lt;formatter type="plain" destfile="${build.dir}/jslint.out" /&gt;
    &lt;fileset dir="web/js" includes="**/*.js" excludes="**/*.pack.js" /&gt;
  &lt;/jslint&gt;</pre>

    <p>
      To check a directory of JavaScript files, whilst warning about whitespace
      issues and undefined variables, as well as predefining a couple of
      global variables we know we'll be using.

      Send the errors to the console, and also emit JUnit XML reports to the build
      directory.
    </p>

    <pre class="prettyprint" id="example-xml">  &lt;jslint options="undef,white"&gt;
    &lt;predef&gt;jQuery,$$&lt;/predef&gt;
    &lt;formatter type="plain" /&gt;
    &lt;formatter type="junit" destfile="${build.dir}/test-reports" /&gt;
    &lt;fileset dir="web/js" includes="**/*.js" excludes="**/*.pack.js" /&gt;
  &lt;/jslint&gt;</pre>

    <p>
      NB: In order to specify a dollar sign, it has to be doubled so that ant
      doesn't attempt to treat it as a property.  If you wanted to list the
      <code>$$</code> function that Prototype uses, you'd have to say
      <code>&lt;predef&gt;$$$$&lt;/predef&gt;</code>!
    </p>

    <script type="text/javascript">prettyPrint()</script>
  </body>
</html>
